/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 * 
 *      http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package argentracker.services;

/**
 * briefly description.
 * 
 * extense description.
 * 
 * @author matero (matero _at_ gmail _dot_ com)
 */
public interface ChppService {

    String HATTRICK_SITE = "http://www.hattrick.org";
    String FILE_SPEC = "/chppxml.axd?file=";
    String SESSION_COOKIES_HEADERS = "Set-Cookie";

    String getRecommendedServer();

    /**
     * Authenticates a user to Hattrick using its loginname and its securityCode.
     * 
     * @param onServer
     *            Hattrick's server to use to authenticate the used. This value <b>MUST</b> be getted using
     *            getRecommendedHattrickServer(). Must not be null.
     * @param withLoginname
     *            User's login name. Must not be null.
     * @param usingReadonlyPassword
     *            User's security code. Must not be null.
     * 
     * @return the session cookies to use when communicating to Hattrick servers.
     * 
     * @throws ChppException
     *             if the authentication fails.
     * 
     * @see "http://www.hattrick.org/Community/CHPP/System/CHPPLogin.aspx"
     */
    String login(String onServer, String withLoginName, String usingReadonlyPassword);
}
